<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<title>Eclipse Build Story</title>
</head>

<body>

<h1>Improving the Eclipse Build Story</h1>
<p>Last modified March 22, 2004</p>
<h2>References</h2>
<ul>
  <li><a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=50816">50816</a> - [plan item] Make workspace builds more scalable</li>
  <li><a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=53565">53565</a> - Improve manual builds</li>
  <li><a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=46039">46039</a> - [Workbench]  Rebuild project when autobuild is on is misleading</li>
  <li><a href="http://dev.eclipse.org/viewcvs/index.cgi/~checkout~/platform-core-home/documents/eclipse3_builder_issues.html">Eclipse 3.0 Build Infrastructure</a></li>
</ul>
<h2>The Status Quo (2.1 and 3.0M7)</h2>
<p>Build-related items show up in 2 places in the UI:</p>
<ul>
  <li><b>Project</b> menu
    <ul>
      <li><b>Build Project</b>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
        (only appears when auto-build is off)</li>
      <li><b>Rebuild Project</b></li>
      <li><b>Build All (Ctrl+B)</b>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
        (only appears when auto-build is off)</li>
      <li><b>Rebuild All</b>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
      </li>
    </ul>
  </li>
  <li>Context menu on project selections
    <ul>
      <li><b>Build Project</b>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
        (only when auto-build is off)</li>
    </ul>
  </li>
</ul>
<p>Semantics:</p>
<ul>
  <li><b>Project &gt; Build Project</b>
    <ul>
      <li>calls <code>IProject.build(INCREMENTAL_BUILD)</code> on just the
        selected project(s)</li>
      <li>does not build out-of-date prerequisite projects</li>
      <li>fails if there are prerequisite projects with no recorded build state</li>
    </ul>
  </li>
  <li><b>Project &gt; Rebuild Project</b>
    <ul>
      <li>calls <code>IProject.build(FULL)</code> on just the selected project(s)</li>
      <li>does not build out-of-date prerequisite projects</li>
      <li>fails if there are prerequisite projects with no recorded build state</li>
    </ul>
  </li>
  <li><b>Project &gt; Build </b><b>All</b>
    <ul>
      <li>calls <code>IWorkspace.build(INCREMENTAL_BUILD)</code></li>
    </ul>
  </li>
  <li><b>Project &gt; Rebuild </b><b>All</b>
    <ul>
      <li>calls <code>IWorkspace.build(FULL_BUILD)</code></li>
    </ul>
  </li>
  <li>Content menu <b>Build Project</b>
    <ul>
      <li>Same as <b>Project &gt; Build Project</b></li>
    </ul>
  </li>
</ul>
<p>Observations:</p>
<ul>
  <li><b>Build Project</b> is quite unhelpful; it often produces useless
    results or fails outright</li>
  <li>When auto-build is on, <b>Rebuild Project</b> calls <code>IProject.build(FULL)</code>
    on just the selected project(s) and does not follow-up with auto-building
    the downstream projects, leaving the workspace in a less-than-fully-built
    state. The next change the user makes will trigger building all downstream
    projects (this behavior has been fixed in 3.0 stream).</li>
  <li>It is anomalous to be removing menu items rather than disabling them when
    auto-build is off</li>
   <li>There is frequent user confusion about the difference between <b>Build</b>
   and <b>Rebuild</b>.</li>
   <li>Users with very large, highly interdependent projects face long build delays
   when building the entire workspace and would like to build smaller
   portions of the workspace more easily.</li>
</ul>
<h2>Proposed Improvements for 3.0</h2>
<p>We propose to make the build story more useful by providing &quot;targeted
builds&quot; which have the flavor of make (or Ant) builds where the user says
what projects they want to end up with in a &quot;built&quot; state and letting
the system figure out what set of prerequisite projects need to be taken into
account. By allowing the user to tell us which project(s) are important to them,
we give them a powerful tool to control how much work gets done when they say
&quot;build&quot;. (This proposal only affects manual builds; it does not change
the way auto-build mode works.)</p>
<p>Summary of proposed changes:</p>
<ul>
  <li>Change semantics of <b>Build Project</b> command to build prerequisites if
    required.</li>
  <li>Replace <b>Rebuild Project</b> and <b>Rebuild All</b> commands with a <b>Clean</b>
    command which discards internal build state and ensures that subsequent
    the build will begin from scratch (same as old <b>Rebuild</b> behavior).</li>
  <li>Add <b>Build Working Set</b> command that builds all projects in the
    working set, and their prerequisites if required</li>
</ul>
<p>Build shows up in same 2 places in UI:</p>
<ul>
  <li><b>Project</b> menu
    <ul>
      <li><b>Build Project</b>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
        (<i>disabled</i> when auto-build is on)</li>
      <li><b>Build All (Ctrl+B)</b>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(<i>disabled</i> when auto-build is on)
      </li>
      <li><b>Build Working Set
        &gt;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
        </b>(<i>disabled</i> when auto-build is on)
        <ul>
          <li><b>MRU list</b> of working sets with dot marking last-built one</li>
          <li><b>Select Working Set...</b>&nbsp;&nbsp;(<i>disabled</i> when auto-build is on)</li>
        </ul>
      </li>
      <li><b>Clean...</b></li>
    </ul>
  </li>
  <li>Context menu on project selections
    <ul>
      <li><b>Build Project</b>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
        (<i>disabled</i> when auto-build is on)</li>
    </ul>
  </li>
</ul>
<p>Semantics:</p>
<ul>
  <li><b>Project &gt; Build Project</b>
    <ul>
      <li>ensures that all selected projects are up-to-date build-wise</li>
      <li>out-of-date prerequisite projects will be automatically brought
        up-to-date</li>
      <li>like <b>Project &gt; Build Working Set &gt; <i>working set</i></b> except no
        working set is created</li>
      <li>disabled when no projects are selected</li>
    </ul>
  </li>
  <li><b>Project &gt; Build All</b>
    <ul>
      <li>unchanged from 2.1</li>
      <li>calls <code>IWorkspace.build(INCREMENTAL_BUILD)</code></li>
      <li>standard key binding Ctrl+B</li>
    </ul>
  </li>
  <li><b>Project &gt; Build Working Set &gt; Select Working Set...</b>
    <ul>
      <li>Presents a dialog to choose a working set, possibly defining one
        in the process. Successful exit causes the selected working set to become the
        current working set and then be built (see next item)</li>
    </ul>
  </li>
  <li><b>Project &gt; Build Working Set &gt; <i>working set</i></b>
    <ul>
      <li>ensures that all projects in working set are up-to-date build-wise</li>
      <li>out-of-date prerequisite projects will be automatically brought
        up-to-date</li>
      <li>let C = transitive closure of working set under prerequisite relation</li>
      <li>calls <code>IProject.build(INCREMENTAL_BUILD)</code> on each project
        in C, but only if the project needs rebuilding</li>
      <li>applies workspace-wide project build order to subset C to determine
        build order</li>
    </ul>
  </li>
  <li>A keybinding can be created for the command <b>Repeat Last Working Set Build</b>.
  This command does not appear as a separate menu item, but is dynamically bound
  to the working set in the MRU list that was most recently built.
  </li>
  <li><b>Project &gt; Clean...</b>
    <ul>
      <li>Cleans up after previously run builders. Presents a dialog explaining a bit what 
      &quot;clean&quot; means, and radio buttons for &quot;Clean all projects&quot; and
        &quot;Clean selected projects&quot;. If the dialog is OKed, asks all builders to 
        forget build states and removes all problem markers from the workspace. The
        next build will start from square one. If autobuild is turned on a build will be
        kicked off immediately.</li>
    </ul>
  </li>
  <li>Context menu <b>Build Project</b>
    <ul>
      <li>same as <b>Project &gt; Build Project</b></li>
    </ul>
  </li>
</ul>
<h2>Explaining How Builds Work to Users</h2>
<p>Here's how we would explain it to users:</p>
You have two modes of working: <i>auto-build</i> mode and <i>manual build</i> mode.
By default, you are in auto-build mode and Eclipse takes care of compiling source 
files automatically. Builds occur automatically in the background every time
you change files in the workspace (for example saving an editor). 
Auto-build is convenient because it means problems view, binaries, etc. are are 
up-to-date at all times. The downside is that in large workspaces auto-builds can be 
time-consuming if you are changing files in projects with lots of downstream 
dependent projects.
</p>
<p>
If auto-build is taking too long and is interfering with ongoing development, it can
be turned off.  Once in manual build mode, the user is in complete control over 
when builds occur and what gets built. <b>Project &gt; Build All (Ctrl+B)</b> 
can be invoked at any time to trigger what auto-build was doing automatically.
This allows you to build up a larger set of changes before invoking 
a build (Eclipse remembers which files have changed so that it does not have to do 
more work than required when you do ask for a build.
</p>
<p>
In large workspaces, building the entire workspace can take a long time if you
make changes with a significant impact on dependent projects.  Often there are 
only a few projects that really matter to you a a given time. You can now simply
select the project or projects that you want to bring up-to-date, and select
<b>Build Project</b> from the context menu or <b>Project</b> menu. This will
build only the selected projects, and any prerequisite projects that need to be
built in order to correctly build the selected projects. Projects that depend on the projects
you build will not be built. If you're familiar with the make tool, or Ant, they work 
the same way.
</p>
<p>
If you're interested in a set of projects, you may find it inconvenient to
be repeatedly selecting several projects in the Navigator. In this case, you 
can choose <b>Project &gt; Build Working Set &gt; Select Working Set... </b>and
choose a working set that contains the projects that you want to have built. This
has the exact same effect as selecting that set of projects in the Navigator and
selecting <b>Build Project</b>. Again, prerequisite projects will be built automatically
if necessary. Recently built working sets appear on the <b>Project &gt; Build Working
Set &gt;</b> submenu, making it fast to switch to any of these. You can allocate
a key binding for the command <b>Repeat Last Working Set Build</b> in the 
<b>Project</b> category of the <b>General &gt; Keys</b> preference page,
if you want a convient way to invoke a working set build.
</p>
<p>
Under normal circumstances, you should have no reason to use the <b>Clean</b>
command.  Eclipse builders are generally incremental - they only build files that
have changed since the last build, or files that are affected by changed files.
This makes Eclipse builds very efficient even when there are large numbers of files.
If something goes wrong and Eclipse loses track of where it was, this incremental 
process may fail to bring a project up to date. If this ever happens, the 
<b>Clean</b> command is there so the user can manually intervene and set 
Eclipse back on the tracks.  This ensures that the next build will recompile all
files over from scratch, as if the builder was running for the very first time. Naturally,
this can be time consuming for large workspaces.  You can selectively <b>Clean</b>
one or more projects if you know which projects are having problems building.
</p>
<h2>Implementation</h2>
<p>The proposed new behavior is included in the 3.0 M8 stable build. A 
&quot;Work in progress&quot; preference page can be used to add back
the removed <b>Rebuild</b> menu actions.  The new behavior has also
been packaged as a separate plug-in that can be run in Eclipse 2.1. Here
is how to use this prototype plug-in (id org.eclipse.ui.newbuild) in Eclipse 2.1:
<ul>
  <li><a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=53565">Get the plug-in</a>
  from the bug report attachment.</li>
  <li>Download the zip file.</li>
  <li>Unzip it and drop the directory named org.eclipse.ui.newbuild into
    your eclipse/plugins/ directory.</li>
  <li>Delete the eclipse/.config subdirectory.</li>
  <li>Customize your workbench perspective to enable the new build commands.
   <b>Window &gt; Customize Perspective</b>; <b>Commands</b> tab; check <b>New Build
        Actions</b> item</li>
    </ul>
  </li>
  <li><b>New Build Project</b>, <b>Build Working Set</b>, and <b>Clean&nbsp;</b>
    now appear on the
    Project menu.</li>
  <li>The new Build Project now appears on the context menu for the selected
    project labeled <b>New Build Project</b>.</li>
</ul>
<p>Comments and feedback are welcome in the bug report and on the
platform-core-dev mailing list.</p>
</body>
</html>